Souls Directory

GET /api/souls-directory/search

Souls Directory

cURL

curl --request GET \
  --url https://api.example.com/api/souls-directory/search

200

{
  "items": [
    {
      "handle": "<string>",
      "slug": "<string>",
      "page_url": "<string>",
      "raw_md_url": "<string>"
    }
  ],
  "handle": "<string>",
  "slug": "<string>",
  "content": "<string>"
}

Search and fetch agent templates from the souls directory.

Authentication

Requires admin or agent authentication.

Search Souls

GET /api/souls-directory/search

Search for agent template entries by handle or slug.

Query Parameters

q · string · default: ""

Search query text

limit · integer · default: "20"

Maximum results to return (1-100)

Response

items · array

Array of soul references

handle · string

Directory handle (e.g., openclaw)

slug · string

Soul slug (e.g., devops-lead)

page_url · string

Public page URL for this soul

raw_md_url · string

Raw markdown URL

Example Request

curl -X GET "https://api.openclaw.ai/api/souls-directory/search?q=devops&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "items": [
    {
      "handle": "openclaw",
      "slug": "devops-lead",
      "page_url": "https://souls.directory/openclaw/devops-lead",
      "raw_md_url": "https://raw.githubusercontent.com/souls-directory/registry/main/openclaw/devops-lead.md"
    },
    {
      "handle": "openclaw",
      "slug": "kubernetes-expert",
      "page_url": "https://souls.directory/openclaw/kubernetes-expert",
      "raw_md_url": "https://raw.githubusercontent.com/souls-directory/registry/main/openclaw/kubernetes-expert.md"
    }
  ]
}

Get Soul Markdown

GET /api/souls-directory/{handle}/{slug} or GET /api/souls-directory/{handle}/{slug}.md

Fetch the full markdown content for a soul template.

Path Parameters

handle · string · required

Directory handle (alphanumeric with hyphens/underscores)

slug · string · required

Soul slug (alphanumeric with hyphens/underscores)

Response

handle · string

Directory handle

slug · string

Soul slug

content · string

Full markdown content of the soul template

Example Request

curl -X GET "https://api.openclaw.ai/api/souls-directory/openclaw/devops-lead" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "handle": "openclaw",
  "slug": "devops-lead",
  "content": "---\nname: DevOps Lead\nrole: Lead DevOps Engineer\ndescription: Experienced DevOps leader specializing in cloud infrastructure and CI/CD\n---\n\n# DevOps Lead\n\nI am an experienced DevOps engineer with expertise in:\n\n- Kubernetes and container orchestration\n- CI/CD pipeline design and implementation\n- Cloud infrastructure (AWS, GCP, Azure)\n- Infrastructure as Code (Terraform, CloudFormation)\n- Monitoring and observability\n\n## Capabilities\n\n- Design and implement scalable cloud architectures\n- Automate deployment pipelines\n- Optimize infrastructure costs\n- Establish SRE best practices\n- Lead incident response and post-mortems\n"
}

Using Soul Templates

Soul templates are agent configuration files that define:

• Agent identity (name, role, description)
• System instructions and behavior
• Tool access and permissions
• Knowledge base references

You can use these templates to:

1. Bootstrap new agents with proven configurations
2. Share agent designs across organizations
3. Discover best practices for different agent roles

Validation

The API validates that handles and slugs:

• Start with an alphanumeric character
• Contain only alphanumeric characters, hyphens, and underscores
• Are not empty

Error Responses

422 Unprocessable Content

{
  "detail": "handle contains unsupported characters"
}

502 Bad Gateway

Returned when unable to fetch the soul markdown from the external directory.

{
  "detail": "Failed to fetch soul markdown: connection timeout"
}